// ==================== src/traits/network_service.rs ====================
//! 网络服务trait定义
//!
//! 定义节点间网络通信的通用接口，支持集群内部的消息传递
//!
//! # 功能特性
//! - 点对点通信：支持向特定节点发送请求
//! - 广播通信：支持向所有节点广播消息
//! - 连接管理：支持动态建立和断开连接
//! - 状态监控：支持连接状态实时查询
//!
//! # 设计原则
//! - 协议无关：不依赖特定网络协议
//! - 零拷贝传输：最小化数据拷贝开销
//! - 异步非阻塞：支持高并发场景
//! - 可扩展性：支持多种网络协议实现

use async_trait::async_trait;
use crate::{Result, ClusterNode};
use serde::{Deserialize, Serialize};

/// 网络请求数据结构
///
/// 封装节点间通信的请求信息，支持多种业务模块的扩展
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct NetworkRequest {
    /// 请求唯一标识符，用于请求追踪和去重
    pub request_id: String,
    /// 源节点ID，标识请求的发送方
    pub source_node_id: String,
    /// 业务模块名称，用于路由到相应的处理器
    pub module: String,
    /// 请求类型，区分不同的业务操作
    pub r#type: String,
    /// 请求体数据，使用二进制格式支持零拷贝传输
    pub body: Vec<u8>,
}

/// 网络响应数据结构
///
/// 封装节点间通信的响应信息，包含完整的执行结果
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct NetworkResponse {
    /// 关联的请求ID，与请求一一对应
    pub request_id: String,
    /// 请求执行是否成功
    pub success: bool,
    /// 错误码，0表示成功，非0表示不同类型的错误
    pub error_code: i32,
    /// 错误信息，提供详细的错误描述
    pub error_message: String,
    /// 响应体数据，使用二进制格式支持零拷贝传输
    pub body: Vec<u8>,
}

/// 网络服务trait
///
/// 定义节点间网络通信的核心接口，支持集群内部的消息传递和状态同步
///
/// # 方法说明
/// 所有方法均为异步，支持高并发场景下的网络通信
#[async_trait]
pub trait NetworkService: Send + Sync + std::fmt::Debug {
    /// 发送请求到指定节点
    ///
    /// # 参数
    /// - `node`: 目标集群节点信息
    /// - `request`: 网络请求数据
    ///
    /// # 返回值
    /// 返回网络响应结果，包含请求执行状态和返回数据
    async fn send_request(&self, node: &ClusterNode, request: &NetworkRequest) -> Result<NetworkResponse>;
    
    /// 广播请求到所有节点
    ///
    /// # 参数
    /// - `request`: 需要广播的网络请求
    ///
    /// # 返回值
    /// 返回所有节点的响应结果集合
    async fn broadcast(&self, request: &NetworkRequest) -> Result<Vec<NetworkResponse>>;
    
    /// 建立与指定节点的网络连接
    ///
    /// # 参数
    /// - `node`: 目标节点信息
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn connect(&self, node: &ClusterNode) -> Result<()>;
    
    /// 断开与指定节点的网络连接
    ///
    /// # 参数
    /// - `node`: 目标节点信息
    ///
    /// # 返回值
    /// 成功返回Ok(())，失败返回错误信息
    async fn disconnect(&self, node: &ClusterNode) -> Result<()>;
    
    /// 检查与指定节点的连接状态
    ///
    /// # 参数
    /// - `node`: 目标节点信息
    ///
    /// # 返回值
    /// 返回连接状态，true表示已连接，false表示未连接
    async fn is_connected(&self, node: &ClusterNode) -> Result<bool>;
}

